home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / documents / ANSI-C / AnnotatedAnnotatedCStandard next >
Text File  |  1994-08-01  |  36KB  |  832 lines
  1.  
  2. From: clive@sco.com (Clive D.W. Feather)
  3. Subject: The Annotated Annotated C Standard
  4. Sender: clive@x.co.uk (Clive Feather)
  5. Date: Tue, 22 Mar 1994 20:22:46 GMT
  6. Organization: Santa Cruz Organization
  7. Lines: 804
  8. Xref: fido.asd.sgi.com comp.lang.c:76863 comp.std.c:11897
  9.  
  10.  
  11. The Annotated Annotated C Standard
  12. ==================================
  13. C.D.W.Feather
  14. =============
  15.  
  16. This is a review of _The_Annotated_ANSI_C_Standard_, annotated by Herbert
  17. Schildt.
  18.  
  19. This review is made possible by the generosity of Raymond Chen
  20. <raymondc@microsoft.com>, who provided the review copy of the book,
  21. and is dedicated to the Dream Inn, Santa Cruz, CA, whose staff
  22. supplied countless cups of coffee while I wrote this review.
  23.  
  24.  
  25. This version was modified on 1994-03-26. Thanks to the following for
  26. pointing out errors:
  27.     Christopher R Volpe <volpe@ausable.crd.ge.com>
  28.     Jutta Degener <jutta@cs.tu-berlin.de>
  29.     Mark-Jason Dominus <mjd@saul.cis.upenn.edu>
  30.     Sue Meloy <suem@hprpcd.rose.hp.com>
  31.  
  32.  
  33. Introduction
  34. ------------
  35. Since _The_Annotated_ANSI_C_Standard_ first appeared, many people have
  36. commented on errors in the book. After reading several of these, I obtained
  37. a copy of the book and have read it in its entirety.
  38.  
  39. Many of these comments might appear to be relatively trivial. In response to
  40. this, I can only point out that the book is commenting on a very carefully
  41. designed document, and one that has to be read precisely. If the annotator
  42. cannot get things right, then the book is not just useless, but is a positive
  43. danger to those who do not have the time to read and analyse every word of the
  44. standard. In other contexts, such as a tutorial on C, some of the errors in
  45. this book could be allowed to pass, but not in this.
  46.  
  47. When I state that no mention is made of a topic, this indicates that I feel
  48. that the topic is at least as important as ones that were commented on; quite
  49. often this refers to the features of the standard which are less easy to
  50. understand.
  51.  
  52. Text quoted directly from the book is indicated by @@ in the left margin.
  53.  
  54.  
  55. General comments
  56. ----------------
  57. Quite often, the book gives the impression that annotations were omitted
  58. because they couldn't be fitted into the format of "standard on the left,
  59. comments on the right". Whilst many pages of the standard have no annotations
  60. at all, there are no pages with annotation but no standard. I note at least
  61. one case below where I believe that a function was not annotated because the
  62. comments on the previous section took up too much space.
  63.  
  64. The front cover of the book shows, amongst much clutter and someone's
  65. half-eaten muffin, page 147 of the standard. It is intriguing to note that,
  66. not only is this the obsolete ANSI standard rather than the ISO standard,
  67. but that it corresponds to half of page 146 in the book.
  68.  
  69. The major divisions of the standard are referred to as "Part 1", "Part 2", etc.
  70. In actual fact, they are "clause 1", "clause 2", and so on. One has to wonder
  71. about an author who can't even get that right.
  72.  
  73.  
  74. Specific comments
  75. -----------------
  76. Numbers at the start of each comment are the ISO subclause numbers of
  77. Schildt's annotations, which are not always the same as the subclause actually
  78. being annotated.
  79.  
  80. 3.10, 3.16, 3.17
  81. A proper understanding of the terms "implementation-defined", "undefined",
  82. and "unspecified", and of the differences between them, is essential to
  83. understanding the limits that the standard puts on the programmer and the
  84. implementor. Unfortunately, the differences are not explained at all, and
  85. the book leaves me wondering why the different terms are used at all.
  86.  
  87. 3.13
  88. @@ However, this limits the total character set to 255 characters.
  89. Actually, it limits it to UCHAR_MAX characters, which is at least 255, but
  90. can be more. There was an opportunity here to explain what multibyte characters
  91. actually are, but it seems to have been missed, possibly because of the lack
  92. of space.
  93.  
  94. 3.14
  95. @@ An object is either a variable or a constant that resides at a physical
  96. @@ memory address.
  97. In C, a constant does not reside in memory (except for some string literals)
  98. and so is not an object.
  99.  
  100.  
  101. 5.1.1.3
  102. The standard is clear that diagnostics are required when syntax rules and
  103. constraints are violated, and are optional otherwise. This is not covered at
  104. all. Instead we get the vague statement that
  105. @@ The standard requires that a compiler issue error messages when an error
  106. @@ in the source code is encountered.
  107. without discussing the different kinds of errors.
  108.  
  109. 5.1.2.2
  110. @@ You are therefore free to declare main() as required by your program.
  111. This statement is immediately followed by the example:
  112.     void main (void)
  113. even though the text of the standard directly opposite states that this is
  114. undefined. Indeed, the text I quote makes me wonder whether Schildt believes
  115. that:
  116.     struct foo { int i; double d; } main (double argc, struct foo argv)
  117. is permitted !
  118.  
  119. Most of the examples in the book declare main() as void. I won't bother to
  120. point them out individually.
  121.  
  122. 5.1.2.2.1
  123. @@ Though most compilers will automatically return 0 when no other return
  124. @@ value is specified (even when main() is declared as void), you should
  125. @@ not rely on this fact because it is not guaranteed by the standard.
  126. Indeed it is not. If main() is declared as void, I don't know of any compiler
  127. that will return 0. Indeed, the standard forbids it to !
  128.  
  129. 5.1.2.3
  130. This section is often called the "as if" rule, because it says that an
  131. implementation may do anything providing that the effect is "as if" the
  132. exact wording of the standard was followed. This is almost completely ignored
  133. in favour of explaining "side effect" and "automatic storage".
  134.  
  135. 5.2.1.2
  136. @@ Therefore, a multibyte character is a character that requires more than
  137. @@ one byte.
  138. Ignoring the fact that "character" and "byte" are synonymous in the standard
  139. (something that is not mentioned in the annotations), the definition of
  140. multibyte character is clear that it *does* include single byte characters.
  141.  
  142. @@ First, the null character may not be used except in the first byte of a
  143. @@ multibyte sequence.
  144. I read this as meaning that the multibyte character <00><94> is legal while
  145. the multibyte character <94><00> is not. In actual fact, the standard states
  146. that a zero byte must not appear in *any* multibyte character other than the
  147. null character (i.e. the end of string indicator). This means that string
  148. operations such as strcpy will work as expected with multibyte character
  149. sequences.
  150.  
  151. There was an opportunity here to explain multibyte characters and how to
  152. use them, something that most books omit. Unfortunately, this one omits it
  153. as well.
  154.  
  155. 5.2.3
  156. @@ In other words, one copy of a library function in memory may not be used
  157. @@ by two or more currently executing programs.
  158. This is blatant nonsense - on most Unix systems, if the same program is
  159. executing several times, all the code is shared by both processes. Indeed,
  160. many go further and share one copy of the standard C library among every
  161. process on the system.
  162.  
  163. What this section of the standard is talking about is re-entrancy. The
  164. functions in the library are not re-entrant, and so may not be called from
  165. within themselves. For example:
  166. * qsort() cannot be called from within the compare function passed to qsort();
  167. * if a signal can be raised within a library function (perhaps by an external
  168.   event such as the user pressing a BREAK key), then the signal handler must
  169.   not call that library function.
  170. The latter rule is particularly important: code using malloc must not call
  171. malloc from within signal handlers.
  172.  
  173. 5.2.4.1
  174. @@ A compound statement is a block of code.
  175. A nice sounding statement, but totally meaningless. A compound statement is
  176. a block of code beginning with { and ending with the matching }. For example,
  177. the body of a function is a compound statement.
  178.  
  179. 5.2.4.2
  180. @@ First, notice that a character is defined as 8 bits (1 byte). All other
  181. @@ types may vary in size, but in C a character is always 1 byte long.
  182. Certainly a character is always 1 byte long, since that is what a byte is
  183. defined as. However, nowhere does the standard require a byte to be 8 bits;
  184. an implementation with 47-bit bytes can conform to the standard.
  185.  
  186. The assumption that 1 byte = 8 bits occurs at several other points in the book.
  187. I won't always bother to point it out.
  188.  
  189. 6.1
  190. The book carefully talks about tokens, and then proceeds to mention
  191. preprocessing tokens, while totally failing to note the difference, or why
  192. both concepts exist. I would have thought that this was exactly the sort of
  193. thing annotation was all about.
  194.  
  195. 6.1.1
  196. @@ No other keywords are allowed in a conforming program.
  197. False. Other keywords are allowed, providing that they either occupy the
  198. implementation namespace (such as "__far"), or that they are only used after
  199. inclusion of a non-standard system header. For example, a compiler could
  200. state that, following "#include <8086.h>", "far" is a keyword. Since no
  201. strictly conforming program can include that header, and providing that "far"
  202. is not treated specially without it, such a compiler would conform to the
  203. standard.
  204.  
  205. Of course, no other keywords are allowed in a *strictly* conforming program.
  206.  
  207. 6.1.2
  208. If one is going to mention that only the first six characters of external
  209. names are significant, one should also mention that the case of those six
  210. characters is not.
  211.  
  212. 6.1.2.1
  213. @@ * File scope begins with the beginning of the file and ends with the end
  214. @@ of the file
  215. @@ * Block scope begins with the opening { of a block and ends with its
  216. @@ associated closing }.
  217. This is not true: while the scopes end as described, they begin, for each
  218. identifier, at the end of its "declarator" (that is, at the comma, equals
  219. sign, or semicolon after it is declared). This is particularly important for
  220. idenfifiers with block scope. Consider this code:
  221.  
  222.     /* Line 1 */ {
  223.     /* Line 2 */    int i = 10;
  224.     /* Line 3 */    {
  225.     /* Line 4 */        int j = i;
  226.     /* Line 5 */        int i = 5;
  227.     /* Line 6 */        printf ("i = %d, j = %d\n", i, j);
  228.     /* Line 7 */    }
  229.     /* Line 8 */ }
  230.  
  231. All three variables have block scope, but they are different:
  232.   outer i: from the "=" on line 2 to the "}" on line 8
  233.   inner i: from the "=" on line 5 to the "}" on line 7
  234.         j: from the "=" on line 4 to the "}" on line 7
  235. In particular, the "i" on line 4 refers to the one in the outer block, and
  236. so j has the value 10, not 5.
  237.  
  238. 6.1.2.2
  239. @@ Identifiers with external linkage are accessible by your entire program
  240. Once again this is in error - for example, an identifier with external linkage
  241. is not accessible in a translation unit that uses the same name with internal
  242. linkage. The point of linkage is to indicate when the same identifier refers
  243. to the same object, yet the annotations omit this entirely.
  244.  
  245. 6.1.2.3
  246. There is no mention of the fact that each structure and union type has its
  247. own namespace, so that more than one structure or union can have a field
  248. with a given name.
  249.  
  250. 6.1.2.5
  251. @@ An unsigned integer expression cannot overflow. This is because there is
  252. @@ no way to represent such an overflow as an unsigned quantity.
  253. More nonsense. An implementation either does or doesn't have a way to represent
  254. overflow - usually integers don't, while floating point may or may not (some
  255. systems have INFINITY values that effectively indicate overflow). However,
  256. an unsigned integer expression cannot overflow because the standard says so -
  257. the choice was made that unsigned integer arithmetic is done modulo some
  258. base (UINT_MAX+1 for unsigned int, ULONG_MAX+1 for unsigned long). There is
  259. no magic about this; it was an arbitrary decision by the authors of the
  260. standard.
  261.  
  262. 6.1.3.4
  263. @@ x = 'A'; /* give x the value 65 */
  264. This comment, and the following text, leave the reader believing that 'A'
  265. must have the value 65, and by extension that C requires the use of ASCII
  266. codes. This is of course false, but it would be hard to tell from the book.
  267.  
  268. This, plus the comments assuming 8-bit bytes, and use of the terms "high byte"
  269. and "low byte" of integers later on, makes me wonder whether a better title
  270. for the book is: _The_ANSI_C_Standard_annotated_for_some_MSDOS_compilers_ :-).
  271.  
  272. 6.1.4
  273. @@ In other words, the executable version of a C program contains a table
  274. @@ that contains the string literals used by the program.
  275. While this is one way to implement strings, it is not the only one. Such a
  276. comment does not belong in a book like this.
  277.  
  278. @@ Further, the effect of changing the string literal table is implementation
  279. @@ dependent. The best practice is to avoid altering the string table.
  280. It's more than just implementation dependent (a term which, by the way, is not
  281. used by the standard), it's completely undefined. You *must* *not* modify a
  282. string literal.
  283.  
  284. 6.2.1.2
  285. A description which is essentially correct is spoilt by the addition of the
  286. words:
  287. @@ In the most general terms, when you convert from a larger integer type to
  288. @@ a smaller type, high-order bytes are lost.
  289. When an integer value is converted to a signed type which can't hold that
  290. value, the result need not be that given by removing some bits. For example,
  291. a rule that converted all such values to the minimum value of the destination
  292. type (SCHAR_MIN, SHORT_MIN, INT_MIN) would be conforming.
  293.  
  294. A simpler way to state what this section means is:
  295. * If the source value can be represented in the destination type, it is
  296.   unaltered.
  297. * Otherwise, if the destination type is unsigned, reduce the value modulo
  298.   U<type>_MAX+1.
  299. * Otherwise the destination type is signed and the value is implementation
  300.   defined.
  301.  
  302. 6.2.1.4
  303. @@ When converting a larger [floating] type into a smaller one, if the value
  304. @@ cannot be represented, information content may be lost.
  305. Actually, unlike integers, such conversions are undefined, and the program
  306. may crash as a result.
  307.  
  308. 6.2.1.5
  309. @@ these automatic conversions are also intuitive.
  310. These conversions have been the subject of much debate. This section would
  311. benefit from a proper explanation of the "value preserving" rules, and why
  312. they were chosen.
  313.  
  314. 6.2.2.1
  315. @@ First, an array name without an index is a pointer to the first element of
  316. @@ the array and is not an lvalue.
  317. This has to be one of the worst expressions of the Rule I have ever seen !
  318. First, there are a number of contexts (such as sizeof) where an array name
  319. does *not* get changed to a pointer. Second, if the decay to a pointer takes
  320. place at all, it takes place whether or not there is an index; for example,
  321. decay takes place when the array name is used as a function argument. Last,
  322. an array name *is* an lvalue; it is the resulting pointer that is not.
  323.  
  324. 6.2.2.3
  325. Considering how often they are used, the rather peculiar way they are
  326. specified, and the need to cast them in some contexts but not others, it is
  327. odd that null pointer constants are not mentioned at all.
  328.  
  329. 6.3
  330. @@ The standard states that when an expression is evaluated, each object's
  331. @@ value is modified only once. In theory, this means the compiler will not
  332. @@ physically change the value of a variable in memory until the entire
  333. @@ expression has been evaluated. In practice, however, you may not want to
  334. @@ rely on this.
  335. The book then in effect goes on to say that "i = ++i + 1" is usually compiled
  336. as if it were "i += 2".
  337.  
  338. As anyone who has survived the "i = i++" thread on comp.lang.c knows, this is
  339. not only nonsense, but dangerous nonsense. The correct way to discuss this
  340. part of the standard is to point out what can and can't be done in a strictly
  341. conforming program, and leave it at that. Suggesting that such code can ever
  342. have a defined answer is asking for trouble.
  343.  
  344. @@ The rest of this section formally defined what type of lvalue can refer to
  345. @@ an object.
  346. Well, in one sense this is true. However, what is important is *why* only some
  347. lvalues can refer to a given object, and the annotations completely skip this.
  348. The reason is, of course, to indicate when a compiler can assume that two
  349. identifiers refer to the same object. For example, in:
  350.  
  351.     char *cp;
  352.     int *ip;
  353.  
  354.     void f (double *d)
  355.     {
  356.         *d = 3.14159;
  357.         *cp = 1;
  358.         *ip = 2;
  359.     }
  360.  
  361. The rules of this section say that the assignment to *cp could potentially
  362. alter *d, and the compiler must generate code that takes that into account,
  363. but the assignment to *ip cannot, and the compiler may assume that *d and *ip
  364. do not overlap. This is called "aliasing", and knowing when aliasing takes
  365. effect is an important factor in correctly optimising code.
  366.  
  367. 6.3.2.2
  368. @@ When no prototype for a function exists, it is not an error if the types
  369. @@ and/or number of parameters and arguments differ. The reason for this
  370. @@ seemingly strange rule is to provide compatibility with older C programs in
  371. @@ which prototypes do not exist.
  372. On the contrary, when no prototype exists, the number of arguments to a call
  373. must be the same as the number of parameters in the function (which cannot
  374. be a varargs function), and the types must be compatible after promotion.
  375. What should have been written is that no error message is required if these
  376. rules are broken.
  377.  
  378. 6.3.2.3
  379. Though this section mentions the existence of the "common initial subsequence"
  380. rule for unions, it does not explain it properly, nor does it mention that
  381. in all other circumstances assigning to one element of a union makes all other
  382. elements have undefined values.
  383.  
  384. 6.3.6
  385. There is no mention of the rule that addition and subtraction of pointers and
  386. integers must yield a pointer to the same array or one past the end of the
  387. array.
  388.  
  389. 6.3.7
  390. @@ When right-shifting a negative value, generally, ones are shifted in (thus
  391. @@ preserving the sign bit), but this is implementation dependent.
  392. The result of signed right shift of a negative number is implementation
  393. defined; there is no suggestion in the standard that shifting in ones is the
  394. "best" thing to do.
  395.  
  396. 6.3.13
  397. There is no mention of the fact that && and || evaluate explicitly left to
  398. right, and stop when the result is known. This would be an opportunity to
  399. discuss sequence points, but the opportunity is missed.
  400.  
  401. 6.3.16.2
  402. When talking about compound assignments (+= etc.), the annotations mention
  403. that "a += b" means the same as "a = a + b", but do not point out that the
  404. two are not equivalent; for example, "*a++ *= 2" is strictly conforming code
  405. which increments a once, while "*a++ = *a++ * 2" is not.
  406.  
  407. 6.3.17
  408. Again, there is no mention of sequence points.
  409.  
  410. 6.5
  411. @@ In simple language, a declarator is the name of the object being declared.
  412. In real C, a declarator is everything about the type and name of the object
  413. except the basic type and storage class. For example, in "static int *p[5];",
  414. the declarator is "*p[5]", and includes the concepts of pointer, array, and
  415. size of array as well as the name.
  416.  
  417. 6.5.1
  418. @@ A variable declared using extern is not a definition.
  419. Not only is this wrong, but the annotations to 6.7.2 directly contradict it,
  420. with the correct example of "extern int count = 10;".
  421.  
  422. @@ In essence, a static local variable is a global variable with its scope
  423. @@ restricted to a single function.
  424. Actually, a static local variable is a global variable with its scope
  425. restricted to some block scope; that is, from the end of its declarator to
  426. the closing } of the block it is declared in.
  427.  
  428. @@ When static is applied to a global variable or function, it causes that
  429. @@ variable or function to have file scope
  430. The global variable or function has file scope whether or not static is
  431. applied to it. The static keyword causes it to have internal linkage, which
  432. is a different matter.
  433.  
  434. @@ The register specifier is only a request to the compiler, which may be
  435. @@ completely ignored.
  436. It can't be completely ignored, because whether or not it affects the way in
  437. which the variable is implemented, it is still illegal to take the address of
  438. an object declared register.
  439.  
  440. 6.5.2.1
  441. There is no mention of the implementation-defined aspects of bit fields.
  442.  
  443. @@ This padding must occur at the end, not at the beginning, of the object.
  444. Padding can occur anywhere except at the beginning of a structure. In
  445. particular, it can occur between two fields. Of course a union can only be
  446. padded at the end.
  447.  
  448. 6.5.3
  449. @@ (Many compilers display a warning about this fragment, but still accept
  450. @@ it.)
  451. @@    const int i = 10;
  452. @@    int *p;
  453. @@    p = &i;
  454. @@    *p = 0; /* modify a const object through p */
  455. Actually, the standard requires a diagnostic for the third line, because
  456. it violates the third dashed item of the constraints of 6.3.16.1. If an
  457. explicit cast had been used in that line, I believe that the assignment
  458. would be strictly conforming. If so, then it is true that the standard does
  459. not require a diagnostic for the last line, but nevertheless it is undefined,
  460. not just something to warn about.
  461.  
  462.  
  463. 6.5.4
  464. @@ The information and constraints in this section are mostly applicable
  465. @@ to compiler implementors.
  466. Since this section defines how to declare arrays, pointers, and procedure
  467. prototypes, one has to wonder what the author actually considers interesting !
  468.  
  469. 6.5.4.3
  470. Considering that it has come up in at least two Defect Reports, I would have
  471. expected some mention of the rule about typedef names within prototypes.
  472.  
  473. 6.5.5
  474. A useful way to think of a type name is as a declaration with the identifier
  475. being declared omitted. So, for example, if v is declared as:
  476.     unsigned char *v[5];
  477. then the type of v is:
  478.     unsigned char *[5];
  479.  
  480. 6.5.7
  481. @@ The general form of an initialization is
  482. @@    type var = initializer;'
  483. Once again, the whole concept of declarators is omitted. While it is true that
  484. that is one form of an initialization, it excludes lines like:
  485.       int a [5] = { 1, 2, 3, 4, 5 };
  486.  
  487. 6.6.4.2
  488. This is another example where the annotations describe a "general form"
  489. which isn't. In this case, it implies that the "default" case label must be
  490. the last one in the switch, and that it can't have an associated "break".
  491. The problem with these "general" forms is that, while they are fine in a
  492. teaching context, they omit all the grubby details that a user of the standard
  493. needs to know, such as fall-through cases, or Duff's Device.
  494.  
  495. I would also have appreciated a warning that ordinary labels are still allowed
  496. within the body of a switch statement, so:
  497.     switch (i)
  498.     {
  499.     /* ... */
  500.     defualt:
  501.         j = 0;
  502.         break;
  503.     }
  504. is legal code, but is *not* the default case of the switch.
  505.  
  506. 6.7.1
  507. @@ To understand the difference between the modern and old forms, here is the
  508. @@ same function defined using both forms:
  509. @@    /* Modern function definition. */
  510. @@    float f (int a, char c)
  511. @@    {
  512. @@      /* ... */
  513. @@    }
  514. @@    /* Old-form function definition. */
  515. @@    float f (a, c)
  516. @@    int a;
  517. @@    char c;
  518. @@    {
  519. @@      /* ... */
  520. @@    }
  521.  
  522. Unfortunately, these two aren't exactly the same. With the modern function
  523. definition, the argument corresponding to c is converted to type char and
  524. passed to the function. With the old-form definition, it is converted to int,
  525. passed to the function as an int, and then converted to char.
  526.  
  527. Why does this matter, you may ask ? Well, it matters when we're trying to
  528. write a prototype for the function. The prototype for the new form definition
  529. is:
  530.     float f (int a, char c);
  531. as you might expect. However, the prototype for the old form is:
  532.     float f (int a, int c);
  533.  
  534. 6.8.2
  535. @@ The #include statement has these two forms:
  536. Actually, it has three forms. While the third is fairly uncommon, it ought at
  537. least to be acknowledged.
  538.  
  539. 6.8.3
  540. Probably just a typographical error, but the expansion near the bottom of the
  541. page is:
  542.   printf ("%d ", ABS (((-20) < 0 ? -(-20) : (-20)));
  543. and should be:
  544.   printf ("%d ", ((-20) < 0 ? -(-20) : (-20)));
  545.  
  546. 6.8.6
  547. There is no mention of the fact that using any #pragma in a translation
  548. unit (this means after #ifdef'd-out code has been removed) prevents it from
  549. being strictly conforming.
  550.  
  551.  
  552. 7.1.2
  553. The title of this subclause is: "Standard headers", but the annotations
  554. begin with: "A header file". This obscures the fairly important point that
  555. the standard headers need not be files; there is at least one implementation
  556. where the effect of the standard headers is known by the compiler, and there
  557. are no such files at all.
  558.  
  559. @@ All conforming C compilers will supply all of the functions described here.
  560. This only applies to "hosted" implementations, and is not true for
  561. "freestanding" implementations.
  562.  
  563. 7.1.3
  564. @@ Frankly, many C programmers are not aware of the rules described in
  565. @@ this section.
  566. Quite right ! Unfortunately, the chance to explain the rules was missed.
  567.  
  568. 7.1.4
  569. @@ If errno is zero, then no error has been detected.
  570. This isn't true at all. No library function will ever set errno to zero, but
  571. if it *is* zero before one is called, it can remain zero even if an error does
  572. occur.
  573.  
  574. 7.1.6
  575. The annotations include an example of offsetof(). Unfortunately, the
  576. explanation of this example assumes that there is no padding in the structure.
  577. If structures had no padding, offsetof() wouldn't be needed because the offset
  578. of a field could be computed from the sizes of the preceeding fields.
  579.  
  580. 7.3
  581. These functions are nearly all locale dependent: whether a character is a
  582. letter depends on the language in use as well as the character set.
  583. Unfortunately, the opportunity to explain this has been omitted in favour of
  584. a long example printing lines like:
  585. @@    x is alphanumeric
  586.  
  587. 7.4.1.1
  588. @@ The setlocale() function sets all or a specified portion of those items
  589. @@ described in the lconv structure
  590. This is true in one sense, but oh so misleading. The setlocale() function
  591. alters the meaning of many of the functions in the standard. For example, it
  592. can change which characters are letters, or it can alter the decimal point
  593. character. It can also affect the order in which strcoll() sorts strings.
  594. In all, there are five "categories" that it can affect. The lconv structure
  595. is affected by two of these, but not the other three, and it is not the only
  596. thing that these two affect.
  597.  
  598. 7.6
  599. The example calls setjmp() using the statement:
  600. @@      result = setjmp (jumpbuf);
  601. Unfortunately, the standard puts strict limits on the places in which setjmp
  602. can be called; essentially it must be one of the four forms:
  603.     while (setjmp (jumpbuf))
  604.     while (setjmp (jumpbuf) < 42)
  605.     while (!setjmp (jumpbuf))
  606.     setjmp (jumpbuf);
  607. [The "while" may be replaced by "if" or "switch", or may be the implicit
  608. while of a "for" statement.]
  609. The example in the annotations, however, doesn't use any of these forms, and
  610. so the compiler must produce a diagnostic for this code.
  611.  
  612. The standard also puts limitations on what can be done with local variables
  613. in functions that call setjmp(). I am surprised to find no mention of these
  614. limitations at all.
  615.  
  616. 7.7
  617. There is no mention of the type sig_atomic_t, and when it should be used.
  618.  
  619. 7.9
  620. @@ The type fpos_t is some type of an unsigned integer.
  621. Actually, not only is there no such requirement in the standard, but fpos_t
  622. was designed for the circumstances when a file position *can't* be fitted
  623. into an unsigned long. The forthcoming Normative Addendum 1 also puts further
  624. requirements on fpos_t which, while compatible with the current standard, can
  625. *not* be implemented if it is an unsigned integer.
  626.  
  627. 7.9.2
  628. @@ Thus, it is permissible for a text stream to treat all characters as part of
  629. @@ one long, uninterrupted line, if it so chooses.
  630. Fine sounding words. I wish I knew what they mean !
  631.  
  632. The standard states that an implementation may treat spaces at the end of lines
  633. in text files specially, and may add and remove zero bytes at the end of binary
  634. files. Neither of these rules are mentioned.
  635.  
  636. 7.9.5.2
  637. There is no mention of fflush(NULL), nor that fflush cannot be applied to
  638. an input stream.
  639.  
  640. 7.9.6.1
  641. @@ Note that if stream is a pointer to stdout,
  642. Just a nit, but stdout is a pointer, and stream cannot point to it.
  643.  
  644. Here, and in many other places, printf() is called with a format of "%lf" and
  645. a corresponding argument which is a double. Unfortunately, the standard states
  646. that "%f" is the correct format for a double, and "%lf" is undefined. This is
  647. a particularly bad sin because the description of the "l" flag is missing
  648. (left page 132 of the book is a repeat of page 131).
  649.  
  650. While I cannot of course just copy the missing text, I can summarise what has
  651. been lost.
  652.  
  653. After the % appear:
  654. - optional flags
  655. - an optional field width
  656. - an optional precision
  657. - an optional "h", "l", or "L"
  658. - a character specifying the conversion type
  659.  
  660. The flags are:
  661. - minus: left justify the conversion within the field width, instead of right
  662.          justify;
  663. - plus:  any signed conversion will begin with a plus or minus sign;
  664. - space: any signed conversion which does not begin with a sign will be
  665.          prefixed with a space; this is ignored if the plus flag also appears;
  666. - hash:  for "o" conversion, ensure that the first digit is a zero;
  667.          for "x" conversion, a non-zero result will begin with "0x";
  668.          for "X" conversion, a non-zero result will begin with "0X";
  669.          for floating-point conversions, there will always be a decimal point
  670.          even if no digits follow it;
  671.          for "g" and "G" conversion, trailing zeroes are retained;
  672.          hash may not appear on any other conversions;
  673. - zero   explained on page 133.
  674.  
  675. The field width is an asterisk or a decimal integer. If the converted value
  676. has fewer characters that the field width, it is padded to the width (unless
  677. altered by the flags, the padding is with spaces on the left). The field width
  678. cannot reduce the width of the converted value. Note that a zero at the start
  679. of the width is the "0" flag; it does not mean that the width is in octal.
  680.  
  681. The precision is a dot followed by an asterisk, a decimal integer, or nothing
  682. (equivalent to zero). It can only appear with certain conversions, and its
  683. meaning varies:
  684. d, i, o, u, x, X: the minimum number of digits to appear
  685. e, E, f:          the number of digits after the decimal point
  686. g, G:             the maximum number of signficant digits
  687. s:                the maximum number of characters to be taken from the string
  688. It must not appear with any other conversion.
  689.  
  690. If the width, precision, or both, is an asterisk, the actual value is taken
  691. from an int argument to the fprintf() function. The arguments are always in
  692. the order:
  693. * width if an asterisk
  694. * precision if an asterisk
  695. * actual value to be converted
  696. A negative width means add the "-" flag and use the absolute value; a negative
  697. precision means that the precision should be treated as if omitted.
  698.  
  699. The optional letters may appear as follows:
  700. h with d, i, o, u, x, X:
  701.   the argument value (which is int or unsigned int) will be converted to
  702.   short or unsigned short before printing;
  703. h with n:
  704.   the argument is a (short *) rather than a (int *);
  705. l with d, i, o, u, x, X:
  706.   the argument is long or unsigned long
  707. l with n:
  708.   the argument is a (long *) rather than a (int *);
  709. L with e, E, f, g, G:
  710.   the argument is a long double rather than a double.
  711. These letters may not appear with any other conversion.
  712.  
  713. 7.9.6.2
  714. Both the examples of scansets don't use a field width. This means that if the
  715. user inputs a line which is too long, it will overflow the buffer with
  716. potentially disasterous results. They also use "fflush(stdin)", which is
  717. undefined.
  718.  
  719. 7.9.7
  720. The annotations talk about "high order byte" and "low order byte" as if an
  721. integer only has two bytes. In any case, these functions are not defined in
  722. terms of "bytes", but in terms of conversion to unsigned char.
  723.  
  724. The first example calls fgetc() and assigns the result to a char variable.
  725. This means that an error or end-of-file will cause the program to loop forever.
  726.  
  727. 7.9.10.2
  728. @@ The following fragment illustrates how files are commonly read:
  729. @@    do {
  730. @@        ch = fgetc (fp);
  731. @@        /* ... */
  732. @@    } while (!feof (fp));
  733. This example suffers from the "Pascal disease". The function feof() does not
  734. mean "end of file has been reached", but means "a previous read hit end of
  735. file and returned EOF". Thus, when the last character of the file is read and
  736. processed, "feof (fp)" will still be false, and the loop will be repeated one
  737. more time. This time, ch will be set to EOF, but there is no indication in
  738. the annotations that this must be treated specially. Only after this EOF has
  739. been processed, probably wrongly - for example, if the file is being copied
  740. to somewhere else, a spurious character will be output - will the call to
  741. feof() return true.
  742.  
  743. 7.9.10.3
  744. @@ Also, for files opened for binary operations, EOF is a valid binary value
  745. @@ and does not necessarily indicate an error or end-of-file condition.
  746. This is dangerous nonsense, caused because the annotations use char variables
  747. instead of ints to hold the results of fgetc(). What the standard says is, in
  748. effect, that fgetc() returns a positive or zero value if it read a character,
  749. and a negative value (EOF) if it reached end-of-file or an error occurred.
  750.  
  751. It is true that EOF, cast to the type unsigned char, is identical to value
  752. that can be read from a binary file (or even a text file). However, this is
  753. just the effect of bad programming; anyone with experience in C file handling
  754. should be aware of this.
  755.  
  756. 7.10.1
  757. @@ Also, remember that if the string does not contain a valid numeric value
  758. @@ as defined by the function, then 0 is returned. Although strtod(),
  759. @@ strtol(), and strtoul() set errno when an out-of-range condition exists,
  760. @@ there is no requirement that errno be set when the string does not contain
  761. @@ a number. Thus, if this is important to your program, you must manually
  762. @@ check for the presence of a number before calling one of the conversion
  763. @@ functions.
  764. Actually, it is quite hard to make such a check, but luckily it is also
  765. unnecessary. If there is no number in the string, all three functions set
  766. *endptr to the original value of nptr, while if there is (even if it is zero)
  767. they set it to point after the last character of the number.
  768.  
  769. 7.10.2
  770. The example appears to assume that time_t is an integral type, and so assigns
  771. the result of time() to a long. In fact, it could be double, and it might be
  772. that the cast always yields zero. To extract a random number from the value
  773. returned by time(), it is necessary to do something like the following, which
  774. constructs an unsigned int from all the bits of a time_t value.
  775.  
  776.     unsigned int random_from_time (time_t t)
  777.     {
  778.         unsigned int i, j, k;
  779.         char *p;
  780.  
  781.         i = 0;
  782.         p = (char *) &t;
  783.         /* Divide t up into pieces each the size of an unsigned int */
  784.         for (k = 0; k + sizeof j <= sizeof t; k += sizeof j)
  785.         {
  786.             /* Copy the bits of the piece into j and add the value to i */
  787.             memcpy ((char *) &j, p + k, sizeof j);
  788.             i += j;
  789.         }
  790.         /* Do the same with any remnant (e.g. if j is 4 bytes and t is 11) */
  791.         if (k < sizeof t)
  792.         {
  793.             j = 0;
  794.             memcpy ((char *) &j, p + k, sizeof t - k);
  795.             i += j;
  796.         }
  797.         return i;
  798.     }
  799.  
  800. 7.10.7 and 7.10.8
  801. @@ Since multibyte characters are implementation-specific, you should refer
  802. @@ to your compiler's user manual for details.
  803. There is a lot that can be said about multibyte and wide characters without
  804. having to know individual encodings, and there is a sore lack of such
  805. tutorial material. It is a great pity to be faced with two almost blank pages
  806. instead.
  807.  
  808. 7.11.4
  809. The annotations use the term "rearrange" when discussing strxfrm(). It should
  810. be noted that the result of strxfrm may be longer than the original string.
  811.  
  812. The example compares two arrays of floats using memcmp. While such a comparison
  813. is strictly conforming, it is not useful - the result of the comparison depends
  814. on the details of the encoding of floats, and is in no way related to which
  815. number is greater or smaller. (For example, it is possible to have an encoding
  816. in which 0 < 2, but 2 > 3, as far as this comparison works. In the same way,
  817. comparing integers with memcmp is equally useless on a little-endian system.)
  818.  
  819. 7.12.2.3
  820. There is no description of mktime and how it can be used to solve problems
  821. like "what day is 100 days after December 25th 1993". This appears to be solely
  822. because there was no room on the page opposite the definition of mktime.
  823.  
  824.  
  825. [END]
  826.  
  827. -- 
  828. Clive D.W. Feather     | Santa Cruz Operation    | If you lie to the compiler,
  829. clive@sco.com          | Croxley Centre          | it will get its revenge.
  830. Phone: +44 923 816 344 | Hatters Lane, Watford   |   - Henry Spencer
  831. Fax:   +44 923 210 352 | WD1 8YN, United Kingdom |
  832.